package com.cit.service;

import java.io.IOException;
import java.io.InputStream;

import javax.xml.soap.SOAPBody;
import javax.xml.soap.SOAPPart;
import javax.xml.transform.Source;

import org.w3c.dom.Document;
/**
 * 
 * @author Lang Yu(lang.yu@hp.com)
 * @time Mar 7, 2011 11:42:06 AM
 * @file SoapService.java
 * @package com.cit.service
 * @version 1.0
 * @see
 * Business Interface class to process the soap messages, it provide some actions to process the
 * request body content.
 */
public interface SoapService {
	/**
	 * Initialize the soap messages with user-defined name space,
	 * @param namespace
	 * @return
	 * @throws Exception
	 */
	public SOAPPart initSOAPPart(String namespace) throws Exception;
	/**
	 * Comments:In our web application, the soap messages will first send to the Source class to construct an
	 * Source object, the Source object is javax.xml.transform.Source, it provide a standard way to
	 * process the xml data with xml Schema.
	 * =====================================
	 * Convert the Source object to a String object, it will convert the Source object's content to
	 * string in java language.
	 * @param source
	 * @return
	 * @throws Exception
	 */
	public String soap2String(Source source) throws Exception;
	/**
	 * Convert the request data to SOAPBody object, SOAPBody is javax.xml.soap.SOAPBody, it is provided 
	 * by JDK 6.0, it can construct a standard soap message's body part. We use this interface to convert
	 * the http request's content data to standard object of SOAPBody type.
	 * @param data: a standard format of soap messages, the root node is <Envelope>
	 * @return
	 */
	public SOAPBody getSOAPBody(String data);
	/**
	 * Comments: we parse the xml with org.w3c.dom.Document class, it is provided by JDK, we parse the request
	 * xml data with the steps below:
	 * 1.Receive the request data and convert the request content to Stream,
	 * 2.Convert the Stream into String class and put the request data in the String class,
	 * 3.Convert the String content into xml Document object, an standard abstract xml file document class
	 * ========================================
	 * Convert the String content into xml Document object;
	 * @param xmlStr
	 * @return
	 */
	public Document stringToDoc(String xmlStr);
	/**
	 * Convert the Document object into String content;
	 * @param doc
	 * @return
	 */
	public String docToString(Document doc);
	/**
	 * Save the document to file in the hard disk, after we parsed the xml request data of SOAP body part,
	 * we create the xml to let the Connect-IT to read, so we must create the xml file on our hard disk,
	 * this interface will create the xml file.When we create the xml file, we didn't convert the string
	 * directly to xml file, the input is xml document and in this way, the xml file will be created with
	 * standard method.
	 * @param doc
	 * @param filePath
	 * @param isNS
	 * @return
	 */
	public boolean saveDoc(Document doc, String filePath, boolean isNS);
	/**
	 * Receive the http request's body content, here the body content is an standard soap message format.
	 * @param in
	 * @return
	 * @throws IOException
	 */
	public String getRequestData(InputStream in) throws IOException;
	/**
	 * Because Connect-IT can not read the xml with W3C name space, so here provide an function to remove
	 * the W3C's namespace, just as "http://www.w3.org/2001/XMLSchema", only left the user-defined name space
	 * in output xml file.
	 * @param orgDoc
	 * @return
	 */
	public Document noW3cDoc(Document orgDoc,String namespace);
	/**
	 * Convert the root node name into <HPCEWS_Incident_insert>
	 * @param orgDoc
	 * @param namespace
	 * @return
	 */
	public Document convertRoot(Document orgDoc,String namespace,String contextName,String servletType);
}
